<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Coding Standards - Fuel Documentation</title>
	<link href="../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../assets/js/nav.js"></script>
	<script type="text/javascript" src="../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('general', '../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>FUEL Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>Coding Standards</h2>

		<p>These standards for code formatting and documentation must be followed by anyone contributing to Fuel. Any contributions that do not meet these guidelines will not be accepted.</p>

		<h3 id="file_formatting">File Formatting</h3>

		<h5 id="closing_php_tag">Closing PHP Tag</h5>

		<p>Files containing only PHP code should always omit the closing PHP tag (?>). This prevents many of the elusive white screens of death.</p>

		<h5 id="indentation">Indentation</h5>

		<p>All indentation should be done using real tabs, NOT spaces.</p>

		<h5 id="line_endings">Line Endings</h5>

		<p>Line endings should be Unix-style LF.</p>

		<h5 id="file_naming">File Naming</h5>

		<p>All file names must be all lower case. No exceptions.</p>

		<h5 id="encoding">Encoding</h5>

		<p>Files should be saved with UTF-8 encoding and the BOM should not be used.</p>

		<h3 id="naming_conventions">Naming Conventions</h3>

		<h5 id="namespaces">Namespaces</h5>

		<p>All core classes must be under the Fuel namespace. You can use sub-namespaces, but they must fall under the Fuel namespace:</p>

<pre class="php"><code>namespace Fuel;
namespace Fuel\Controller;
namespace Fuel\Session;</code></pre>

		<p>If for some reason you need to include multiple namespaces in the same file, you must use curly braces around the entire namespace. However, we strongly discourage this, and it should not be used.</p>

<pre class="php"><code>namespace Fuel
{
    class Foo {
        // Code here
    }
}

namespace Fuel\Bar
{
    class Hello {
        // Code here
    }
}</code></pre>

		<h5 id="classes">Classes</h5>

		<p>Class names must underscores to separate words. You should never use CamelCase (except in very rare cases). Each word in the class name should begin with a capital letter.</p>

		<p>The underscores in the class names will be replaced by a directory separator during autoloading and that used as the file path. Here is an example:</p>

<pre class="php"><code>namespace Fuel;

// ------------------------------------------------------------------------

class Session {

}</code></pre>

<pre class="php"><code>namespace Fuel;

// ------------------------------------------------------------------------

class Session_Cookie extends Session_Driver {

}</code></pre>

		<p>This would result in the following file path:</p>

<pre class="php"><code>core/classes/fuel/session.php
core/classes/fuel/session/cookie.php</code></pre>

		<h5 id="methods">Methods</h5>

		<p>Like class names, method names should use underscores to separate words, not CamelCase. Method names should also be all lower case. Protected and private methods should be prefixed with an underscore to enhance code readability.</p>

<pre class="php"><code>class Session {

    public static function get_flash($name, $data)
    {
        // Some code here
    }

}</code></pre>

<pre class="php"><code>class View {

	// Array of global view data
	protected static $_global_data = array();

	protected static function capture($view_filename, array $view_data)
	{
		// Some code here
	}

}</code></pre>

		<h5 id="variables">Variables</h5>

		<p>Variable names should be concise, and contain only lower case letters and underscores. Loop iterators should be short, preferably a single character.</p>

<pre class="php"><code>$first_name
$buffer
for ($i = 0; $i < $max; $i++)</code></pre>

		<h5 id="constants">Constants</h5>

		<p>Constants follow the same guide lines as variables, with the exception that constants should be all upper case.</p>

<pre class="php"><code>MY_CONSTANT
TEMPLATE_PATH
TEXT_DEFAULT</code></pre>

		<h3 id="keywords">Keywords</h3>

		<p>Keywords such as true, false, null, as, etc should be all lower case, as upper case is reserved for constants.</p>

<pre class="php"><code>$var = true;
$var = false;
$var = null;
foreach ($array as $key => $value)
public function my_function(array $array)
function my_function($arg = null)</code></pre>

		<h3 id="control_structures">Control Structures</h3>

		<p>The structure keywords such as if, for, foreach, while, switch should be followed by a space as should parameter/argument lists and values. Braces should be placed on a new line, and break should have the same tab as its case.</p>

<pre class="php"><code>if ($arg === true)
{
	//do something here
}
elseif ($arg === null)
{
	//do something else here
}
else
{
	//catch all do something here
}
foreach ($array as $key => $value)
{
	//loop here
}
for ($i = 0; $i < $max; $i++)
{
	//loop here
}
while ($i < $max)
{
	//loop here
}
switch ($var)
{
	case 'value1':
		//do something here
	break;
	default :
		//do something here
	break;
}</code></pre>

		<h3 id="comparison_logical">Comparisons, Logical operators</h3>

		<p>Comparing function/method returns and variables should be type aware, for example some functions may return false, and when comparing this return the type sensitive operators such as === or !==. Additionally, use of and or or is preferred over && or || for readability. In some cases this cannot be avoided and the use of && or || as its required may be used.</p>

<pre class="php"><code>if ($var === false and $other_var == 'some_value')
if ($var === false or false === my_function())</code></pre>

		<h3 id="white_space">White Space</h3>

		<h5 id="indentation">Indentation</h5>

		<p>Tab (not soft tabs) indentation is required.</p>

		<h5 id="class_interface">Class/Interface Declarations</h5>

		<p>Class/interface declarations have the opening brace on the same line:</p>

<pre class="php"><code>class Session {

}</code></pre>

		<h5 id="function_method">Function/Method Declarations</h5>

		<p>The function/method opening brace must always begin on a new line and have the same indentation as its structure.</p>

<pre class="php"><code>class Session {

	public static function get_flash($name, $data)
	{
		// Some code here
	}

}</code></pre>

		<h5 id="variables">Variables</h5>

		<p>When initializing variables do not do them on a single line. To enhance code readability these should each be on a separate line.</p>

<pre class="php"><code>$var = ''; //do each on its own line
$other_var = ''; //do each on its own line</code></pre>

		<h5 id="brackets_parenthesis">Brackets and Parenthesis</h5>

		<p>No space should come before or after the initial bracket/parenthesis. There should not be a space before closing bracket/parenthesis.</p>

<pre class="php"><code>$array = array(1, 2, 3, 4);
$array['my_index'] = 'something';
for ($i = 0; $i < $max; $i++)</code></pre>

		<h5 id="concatenation">Concatenation</h5>

		<p>String concatenation should not contain spaces around the joined parts</p>

<pre class="php"><code>//yes
$string = 'my string '.$var.' the rest of my string';

//no
$string = 'my string ' . $var . ' the rest of my string';</code></pre>

		<h5 id="operators">Operators</h5>

<pre class="php"><code>$var = 'something';
if ($var == 'something') //space before and after operator
$var++; // no space before
++$var; //no space after
$var = $some_var + $other_var; //space before and after operator</code></pre>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel PHP</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>
